Skip to content

Document CI and pull request integration - #79

Closed
smf-h wants to merge 3 commits into
tt-a1i:mainfrom
smf-h:docs/ci-integration
Closed

Document CI and pull request integration#79
smf-h wants to merge 3 commits into
tt-a1i:mainfrom
smf-h:docs/ci-integration

Conversation

@smf-h

@smf-h smf-h commented Aug 16, 2026

Copy link
Copy Markdown

Problem and value

Archify already has stable JSON receipts and repository CI jobs, but contributors need a reusable example for validating diagrams, uploading receipts, producing trusted artifacts, and checking package freshness.

This PR documents those existing automation boundaries in English and Chinese and links the guide from the pull-request template.

Scope

  • Added docs/ci-integration.md.
  • Added the matching Chinese guide at docs/ci-integration.zh-CN.md.
  • Added one link from .github/PULL_REQUEST_TEMPLATE.md.
  • No workflow, renderer, schema, CLI, generated artifact, or archify.zip changes.

Non-goals

  • No new GitHub Actions workflow.
  • No change to receipt formats or exit codes.
  • No automatic PR commenting or artifact publishing.

Tests run

  • node bin/archify.mjs doctor — passed.
  • node bin/archify.mjs guide "Show an API request with a Redis cache miss" --json — passed.
  • node bin/archify.mjs validate sequence examples/cache-miss-request.sequence.json --quality showcase --json — passed: 9/9 checks, 0 errors, 0 warnings.
  • Relative documentation targets were checked locally.
  • npm test — the repository suite reached two environment-specific failures on Windows: preview termination expects a clean SIGTERM exit, and the Cursor archive test requires the Unix unzip executable. The documentation-related checks passed.

Generated artifacts

None. This PR changes documentation only; archify.zip remains fresh.

Visual evidence

Not applicable.

Review follow-up

Addressed all requested items:

  • Replaced the relative PR-template link with the canonical repository/blob URL.
  • Corrected both GitHub Actions examples and both deliver snippets to use examples/agent-tool-call.workflow.json from working-directory: archify.
  • Removed the link to the separate unmerged troubleshooting PR and linked the existing delivery contract instead.
  • Narrowed package-freshness wording: docs outside archify/ do not require a zip rebuild; documentation inside the packaged archify/ tree, including references, examples, and SKILL.md, does.
  • Stated that scripts/build-zip.sh runs from the repository root.
  • Removed trailing blank lines from both new Markdown files.

Fresh verification:

  • node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json workflow.html --quality showcase --json — passed: 9/9 checks, 0 errors, 0 warnings.
  • Both English and Chinese documented input paths resolve from archify/.
  • Changed-file link and trailing-whitespace checks pass.
  • No packaged files changed, so archify.zip was not rebuilt.

@smf-h smf-h changed the title docs: document CI and pull request integration Document CI and pull request integration Aug 16, 2026
@smf-h
smf-h marked this pull request as draft August 16, 2026 13:30
@smf-h
smf-h marked this pull request as ready for review August 16, 2026 13:38
@tt-a1i

tt-a1i commented Aug 17, 2026

Copy link
Copy Markdown
Owner

Thanks for documenting the CI and pull-request workflow in both languages. I merged this head with the current main locally and the full suite passes 629/629. The overall receipt-handling guidance is useful, but I found several documentation paths that need correction before merge:

  1. The link added to .github/PULL_REQUEST_TEMPLATE.md does not work in its intended surface. Once the template is copied into a PR body, ../docs/ci-integration.md resolves to https://github.com/tt-a1i/archify/docs/ci-integration.md, which returns 404. Please use a repository/blob URL that remains valid from a PR body.

  2. The Chinese GitHub Actions example runs from working-directory: archify but validates ../examples/agent-tool-call.workflow.json. That file does not exist and the documented command exits 1 with input/read. The English Action example correctly uses examples/agent-tool-call.workflow.json.

  3. Both English and Chinese deliver snippets also use ../examples/agent-tool-call.workflow.json while invoking node bin/archify.mjs, which implies the archify/ working directory. These commands reproduce the same ENOENT failure. Please use examples/... or explicitly establish a different working directory and adjust the CLI path consistently.

  4. Both guides link to troubleshooting documents that are not present in this PR or on current main: docs/troubleshooting.md and docs/troubleshooting.zh-CN.md. Please remove/defer those links or resolve the dependency on the separate unmerged PR before merging this one.

The package-freshness wording should also be narrowed. Documentation inside the packaged archify/ tree, including references and examples, does require rebuilding archify.zip; only documentation changes outside the packaged tree are exempt. Please also state that scripts/build-zip.sh is run from the repository root.

Small cleanup: git diff --check reports a blank line at EOF in both new Markdown files. There are currently no GitHub check results on this head, so please attach refreshed command receipts after updating both language versions.

@smf-h

smf-h commented Aug 17, 2026

Copy link
Copy Markdown
Author

Addressed the maintainer review comments in the latest commit. The updated PR description contains the exact verification commands and results.

@tt-a1i

tt-a1i commented Aug 20, 2026

Copy link
Copy Markdown
Owner

Thanks for addressing the previous review feedback. I rechecked the latest revision against the current main: the documented validate, deliver, and compare commands all run successfully, the English and Chinese links resolve, and the full suite passes 655/655 after a local merge. The documentation itself looks ready.

The branch is currently four main-branch commits behind and GitHub reports no checks for this head. Please update the branch with the current main so the remote CI suite can run. If those checks are green, this should be ready to approve and merge without further documentation changes.

@tt-a1i

tt-a1i commented Aug 20, 2026

Copy link
Copy Markdown
Owner

Thank you again for the work you put into this PR, especially for patiently addressing the earlier review feedback.

After taking another look at the use case, I don't think we should add a separate CI integration guide right now. The workflow here assumes that a repository already contains the full archify/ source tree, so it mainly applies to this repository or a complete fork. Most people use Archify as an installed Skill, which means they cannot copy this workflow into their own project as-is. A fair amount of the remaining material also overlaps with CONTRIBUTING.md and the delivery contract, and maintaining two more mirrored documents would make those instructions easier to drift apart.

This is a product-scope decision rather than a problem with the care you put into the documentation, so I would rather close the PR than ask you to keep revising something we are not ready to support properly.

If you are still interested in contributing, #95 would be a very welcome improvement. It focuses on making the English and Chinese READMEs easier for new users to understand by adding a scenario-first chooser, while keeping the current hero and visual introduction unchanged. You would be very welcome to work on that one.

Thanks again for the contribution and for being responsive throughout the review.

@tt-a1i tt-a1i closed this Aug 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants